JIIT Placement Alerts

Documentation

Back to Home
Live GitHub
Getting Started

Architecture & Design

API Architecture & Endpoints
Error Handling & Rate Limiting REST API Endpoints Server Architecture Telegram Bot API
Data Flow & Processing Pipeline
Email Processing Orchestration Notification Flow Distribution Update Flow Processing
Database Schema & Data Model
Collection Schemas & Field Definitions Data Flow & Collection Relationships Indexing Strategy & Performance Optimization Query Patterns & Practical Examples
Service Architecture
Administrative Services Content Processing Services Core Services Formatting Services
Deployment Architecture Design Principles

Core Services

Email Processing Services
Email Notice Service Notice Formatter Service Placement Notification Formatter Placement Service
Database Service Notification Service Telegram Service Web Push Service

Data Processing & Content Extraction

Content Formatting & Enhancement Email Processing & Classification LLM Powered Content Extraction Statistics Calculation & Analytics

Server Components

Scheduler Server Telegram Bot Server Webhook Server
API Reference
Configuration & Environment
Database Schema & Models
Deployment & Operations
Development & Contributing
Troubleshooting & FAQ
Home Projects JIIT Placement Alerts Architecture & Design API Architecture & Endpoints REST API Endpoints

REST API Endpoints

Referenced Files
app/main.pyapp/servers/webhook_server.pyapp/servers/bot_server.pyapp/servers/scheduler_server.pyapp/services/web_push_service.pyapp/services/database_service.pyapp/core/config.pydocs/API.mdapp/requirements.txt
#

Table of Contents#

  1. Introduction

  2. Project Structure

  3. Core Components

  4. Architecture Overview

  5. Detailed Component Analysis

  6. Dependency Analysis

  7. Performance Considerations

  8. Troubleshooting Guide

  9. Conclusion

  10. Appendices

#

Introduction#

This document provides comprehensive documentation for the REST API endpoints exposed by the webhook server, along with related internal endpoints and integration patterns. It covers:

  • GET / (root health)

  • GET /health (detailed health)

  • POST /api/push/subscribe (web push subscription)

  • POST /api/push/unsubscribe (web push unsubscription)

  • GET /api/stats (statistics aggregation)

  • POST /api/notify (broadcast notifications)

  • POST /api/notify/telegram (Telegram-only notifications)

  • POST /api/notify/web-push (Web Push-only notifications)

  • GET /api/push/vapid-key (VAPID public key for web push)

It explains request/response schemas, query parameters, authentication requirements, FastAPI-based implementation, request validation, response formatting, webhook endpoint for Telegram integration, web push subscription management, statistics retrieval with filtering options, error response formats, status codes, and rate limiting strategies. Curl examples and integration patterns with external systems are included.

#

Project Structure#

The webhook server is implemented using FastAPI and exposes multiple endpoints under the /api path. It integrates with dependency-injected services for database operations, notification dispatch, and web push delivery. The CLI entry point supports running the webhook server independently.

graph TB subgraph "CLI" Main["app/main.py
Entry point"] end subgraph "Webhook Server" WSServer["app/servers/webhook_server.py
FastAPI app"] Health["GET /, GET /health"] PushSub["POST /api/push/subscribe"] PushUnsub["POST /api/push/unsubscribe"] VapidKey["GET /api/push/vapid-key"] Notify["POST /api/notify"] NotifyTG["POST /api/notify/telegram"] NotifyWP["POST /api/notify/web-push"] Stats["GET /api/stats"] end subgraph "Services" DB["DatabaseService"] WP["WebPushService"] Notif["NotificationService"] end Main --> WSServer WSServer --> DB WSServer --> WP WSServer --> Notif

Diagram sources

Section sources

#

Core Components#

  • FastAPI application factory with dependency injection for database, notification, and web push services.

  • Pydantic models for request/response schemas.

  • Dependency providers for services via FastAPI Depends.

  • CORS middleware enabled for cross-origin requests.

  • Health endpoints returning standardized status objects.

  • Statistics endpoints aggregating data from the database.

  • Web push subscription endpoints guarded by availability of web push configuration.

  • Notification endpoints dispatching to Telegram and/or Web Push channels.

Section sources

#

Architecture Overview#

The webhook server composes services at startup and exposes REST endpoints. Requests are validated by Pydantic models, and responses are returned as JSON. Services are injected via FastAPI’s dependency system. Web push requires VAPID keys and the pywebpush library; otherwise endpoints return 501 Not Implemented.

sequenceDiagram participant Client as "External Client" participant API as "FastAPI App" participant Dep as "Depends()" participant DB as "DatabaseService" participant WP as "WebPushService" participant Notif as "NotificationService" Client->>API : "HTTP Request" API->>Dep : "Resolve dependencies" Dep-->>API : "DB, WP, Notification instances" API->>DB : "Read/write operations" API->>WP : "Web push operations" API->>Notif : "Broadcast/send notifications" API-->>Client : "HTTP Response (JSON)"

Diagram sources

#

Detailed Component Analysis#

GET /#

  • Purpose: Root health check endpoint.

  • Response model: HealthResponse with status and version.

  • Typical response: {“status”: “ok”, “version”: “1.x.x”}.

  • Status codes: 200 OK.

Section sources

GET /health#

  • Purpose: Detailed health status including service checks.

  • Response model: HealthResponse with status and version.

  • Typical response: {“status”: “healthy”, “version”: “1.x.x”}.

  • Status codes: 200 OK.

Section sources

POST /api/push/subscribe#

  • Purpose: Subscribe a user to web push notifications.

  • Authentication: None (endpoint is public).

  • Request body: PushSubscription (endpoint, keys, optional user_id).

  • Response: {“success”: true/false}.

  • Validation: Raises HTTP 501 if web push is not configured; raises HTTP 500 on exceptions.

  • Status codes: 200 OK, 500 Internal Server Error, 501 Not Implemented.

sequenceDiagram participant Client as "Client" participant API as "FastAPI" participant WP as "WebPushService" Client->>API : "POST /api/push/subscribe" API->>WP : "save_subscription(user_id, subscription)" WP-->>API : "success" API-->>Client : "{success : boolean}"

Diagram sources

Section sources

POST /api/push/unsubscribe#

  • Purpose: Unsubscribe a user from web push notifications.

  • Authentication: None.

  • Request body: PushSubscription (endpoint, keys, optional user_id).

  • Response: {“success”: true/false}.

  • Validation: Raises HTTP 501 if web push is not configured; raises HTTP 500 on exceptions.

  • Status codes: 200 OK, 500 Internal Server Error, 501 Not Implemented.

sequenceDiagram participant Client as "Client" participant API as "FastAPI" participant WP as "WebPushService" Client->>API : "POST /api/push/unsubscribe" API->>WP : "remove_subscription(user_id, endpoint)" WP-->>API : "success" API-->>Client : "{success : boolean}"

Diagram sources

Section sources

GET /api/push/vapid-key#

  • Purpose: Retrieve the VAPID public key for client-side web push subscription.

  • Authentication: None.

  • Response: {“publicKey”: “<VAPID_PUBLIC_KEY>”}.

  • Validation: Raises HTTP 501 if web push is not configured or VAPID key is missing.

  • Status codes: 200 OK, 501 Not Implemented.

Section sources

POST /api/notify#

  • Purpose: Broadcast a notification to configured channels (defaults to Telegram and Web Push).

  • Authentication: None.

  • Request body: NotifyRequest (message, optional title, optional channels array).

  • Response model: NotifyResponse (success: boolean, results: dict).

  • Validation: Raises HTTP 501 if notification service is not configured; raises HTTP 500 on exceptions.

  • Status codes: 200 OK, 500 Internal Server Error, 501 Not Implemented.

Section sources

POST /api/notify/telegram#

  • Purpose: Send a notification via Telegram only.

  • Authentication: None.

  • Request body: NotifyRequest (message, optional title, channels ignored).

  • Response: {“success”: true/false}.

  • Validation: Raises HTTP 501 if notification service is not configured; raises HTTP 500 on exceptions.

  • Status codes: 200 OK, 500 Internal Server Error, 501 Not Implemented.

Section sources

POST /api/notify/web-push#

  • Purpose: Send a notification via Web Push only.

  • Authentication: None.

  • Request body: NotifyRequest (message, optional title, channels ignored).

  • Response: {“success”: true/false}.

  • Validation: Raises HTTP 501 if notification service is not configured; raises HTTP 500 on exceptions.

  • Status codes: 200 OK, 500 Internal Server Error, 501 Not Implemented.

Section sources

GET /api/stats#

  • Purpose: Retrieve aggregated statistics (placement, notices, users).

  • Authentication: None.

  • Response model: StatsResponse (placement_stats, notice_stats, user_stats).

  • Validation: Raises HTTP 501 if database service is not configured.

  • Status codes: 200 OK, 501 Not Implemented.

sequenceDiagram participant Client as "Client" participant API as "FastAPI" participant DB as "DatabaseService" Client->>API : "GET /api/stats" API->>DB : "get_placement_stats(), get_notice_stats(), get_users_stats()" DB-->>API : "stats dicts" API-->>Client : "StatsResponse JSON"

Diagram sources

Section sources

Additional Internal Endpoints#

  • POST /webhook/update: Trigger unsent notice dispatch via notification service. Returns {“success”: true, “result”: …}. Raises HTTP 501 if services not configured; HTTP 500 on exceptions.

Section sources

#

Dependency Analysis#

  • FastAPI app lifecycle manages service initialization and cleanup.

  • Dependency injection resolves DatabaseService, WebPushService, and NotificationService.

  • WebPushService requires VAPID keys and pywebpush; otherwise endpoints return 501.

  • DatabaseService provides statistics and user operations used by stats endpoints.

graph LR App["FastAPI App"] --> DB["DatabaseService"] App --> WP["WebPushService"] App --> Notif["NotificationService"] WP --> Vapid["VAPID Keys"] Notif --> DB

Diagram sources

Section sources

#

Performance Considerations#

  • Web push broadcasting iterates over active users and their subscriptions; consider batching and exponential backoff for large subscriber bases.

  • Database queries for stats should leverage indexes on frequently queried fields (e.g., timestamps, sent flags).

  • Notification dispatch should be asynchronous to avoid blocking requests.

  • Enable CORS appropriately for production origins to reduce preflight overhead.

#

Troubleshooting Guide#

Common issues and resolutions:

  • Web push not configured:

    • Symptom: 501 Not Implemented on /api/push/* and /api/push/vapid-key.

    • Resolution: Set VAPID_PRIVATE_KEY, VAPID_PUBLIC_KEY, VAPID_EMAIL and ensure pywebpush is installed.

  • Missing database:

    • Symptom: 501 Not Implemented on /api/stats.

    • Resolution: Ensure MONGO_CONNECTION_STR is configured and reachable.

  • Notification service not configured:

    • Symptom: 501 Not Implemented on /api/notify*.

    • Resolution: Verify Telegram credentials and ensure NotificationService is constructed with required channels.

  • Rate limiting:

    • The project documentation mentions rate limits for bot commands and REST API. For FastAPI, implement rate limiting middleware or use a gateway/proxy to enforce limits.

Section sources

#

Conclusion#

The webhook server provides a robust REST API surface for health checks, web push subscription management, statistics retrieval, and notification dispatch. It leverages FastAPI for request validation and dependency injection for maintainable service composition. Proper configuration of VAPID keys and database connectivity is essential for full functionality.

#

Appendices#

Request/Response Schemas and Validation#

  • HealthResponse: status (string), version (string).

  • PushSubscription: endpoint (string), keys (object with p256dh and auth), user_id (integer, optional).

  • NotifyRequest: message (string), title (string, optional), channels (array of strings, optional).

  • NotifyResponse: success (boolean), results (object).

  • StatsResponse: placement_stats (object), notice_stats (object), user_stats (object).

Section sources

Authentication and Security#

  • Public endpoints: No authentication required.

  • Web push endpoints guard against misconfiguration by returning 501 when web push is disabled.

  • Production deployment should enforce authentication and rate limiting at the network or gateway level.

Section sources

Integration Patterns#

  • Telegram webhook integration:

    • The bot server handles Telegram commands and user management. While the webhook server does not expose a Telegram webhook endpoint, administrators can trigger updates via /webhook/update to dispatch unsent notices.

  • Web push integration:

    • Clients obtain VAPID public key via /api/push/vapid-key, create a subscription, then POST to /api/push/subscribe. Subscriptions are stored and used for broadcasts.

Section sources

Curl Examples#

Section sources

Environment Configuration#

  • Required for web push: VAPID_PRIVATE_KEY, VAPID_PUBLIC_KEY, VAPID_EMAIL.

  • Required for database: MONGO_CONNECTION_STR.

  • Required for notifications: TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID.

Section sources

Previous Error Handling & Rate Limiting
Next Server Architecture